---
title: "User Model"
description: "Core user data model for MentraOS Cloud"
---

## Overview

The User model is the central data structure representing MentraOS users. It stores authentication data, preferences, installed apps, and system settings.

## Location

`packages/cloud/src/models/user.model.ts`

## Schema Structure

### Core Fields

```typescript
{
  email: string,                    // Primary identifier
  runningApps: string[],           // Currently active app package names
  appSettings: Map<string, AppSetting[]>, // Per-app user settings
  augmentosSettings: {...},        // System-wide settings
  location?: Location,             // Last known location
  installedApps?: InstalledApp[],  // User's installed apps
  organizations?: ObjectId[],      // Organization memberships
  defaultOrg?: ObjectId,           // Primary organization
  onboardingStatus?: Record<string, boolean>, // App onboarding tracking
  glassesModels?: string[]         // Connected glasses history
}
```

### MentraOS Settings

System-wide user preferences:

```typescript
augmentosSettings: {
  // Audio Settings
  useOnboardMic: boolean,          // Use glasses microphone
  bypassVad: boolean,              // Bypass voice activity detection
  bypassAudioEncoding: boolean,    // Skip audio encoding
  enforceLocalTranscription: boolean, // Force on-device transcription

  // Display Settings  
  brightness: number,              // Display brightness (0-100)
  autoBrightness: boolean,         // Automatic brightness adjustment
  dashboardHeight: number,         // Dashboard UI height
  dashboardDepth: number,          // Dashboard UI depth
  alwaysOnStatusBar: boolean,      // Persistent status bar

  // System Settings
  contextualDashboard: boolean,    // Context-aware dashboard
  headUpAngle: number,            // Head-up detection angle
  sensingEnabled: boolean,         // Environmental sensing
  metricSystemEnabled: boolean     // System metrics collection
}
```

### Location Data

```typescript
location: {
  lat: number,                     // Latitude
  lng: number,                     // Longitude  
  accuracy?: number,               // Accuracy in meters
  timestamp?: Date                 // Last update time
}
```

### Installed Apps

```typescript
installedApps: [{
  packageName: string,             // App identifier
  installedDate: Date,             // Installation timestamp
  lastActiveAt?: Date              // Last usage timestamp
}]
```

## Instance Methods

### App Management

#### `installApp(packageName: string)`
Installs an app for the user.
```typescript
await user.installApp('com.translator.app');
```

#### `uninstallApp(packageName: string)`
Removes an app from user's installed apps.
```typescript
await user.uninstallApp('com.translator.app');
```

#### `isAppInstalled(packageName: string)`
Checks if an app is installed.
```typescript
const installed = user.isAppInstalled('com.translator.app');
```

### Running Apps

#### `addRunningApp(appName: string)`
Marks an app as currently running.
```typescript
await user.addRunningApp('com.translator.app');
```

#### `removeRunningApp(appName: string)`
Removes app from running list.
```typescript
await user.removeRunningApp('com.translator.app');
```

#### `isAppRunning(appName: string)`
Checks if an app is currently active.
```typescript
const running = user.isAppRunning('com.translator.app');
```

### Settings Management

#### `updateAppSettings(appName: string, settings: Array)`
Updates user's settings for a specific app.
```typescript
await user.updateAppSettings('com.translator.app', [
  { key: 'targetLanguage', value: 'es' },
  { key: 'autoDetect', value: true }
]);
```

#### `getAppSettings(appName: string)`
Retrieves user's settings for an app.
```typescript
const settings = user.getAppSettings('com.translator.app');
```

### Location

#### `setLocation(location: Location)`
Updates user's location.
```typescript
await user.setLocation({
  lat: 37.7749,
  lng: -122.4194,
  accuracy: 10,
  timestamp: new Date()
});
```

## Static Methods

### `findOrCreateUser(email: string)`
Finds existing user or creates new one.
```typescript
const user = await User.findOrCreateUser('user@example.com');
```

### `findByEmail(email: string)`
Finds user by email address.
```typescript
const user = await User.findByEmail('user@example.com');
```

## Indexes

- **email**: Unique index for authentication
- **organizations**: For organization queries
- **installedApps.packageName**: For app usage analytics

## Relationships

### Organizations
Users can belong to multiple organizations:
- Personal organization (default)
- Company organizations
- Shared app organizations

### Apps
Two types of app relationships:
- **Installed Apps**: Apps the user has added
- **Running Apps**: Apps currently active in session

### Gallery Photos
Referenced by GalleryPhoto model using userId.

## Security Features

### Data Sanitization
All user input is sanitized using MongoSanitizer:
- Prevents NoSQL injection
- Validates data types
- Strips dangerous operators

### Field Protection
Sensitive fields are never exposed:
- Password hashes
- API tokens
- Internal IDs

## Migration Support

The model supports gradual migration from legacy fields:

### Legacy Fields (Deprecated)
```typescript
profile?: {
  company?: string,
  website?: string,
  contactEmail?: string,
  description?: string,
  logo?: string
}
```

These are being migrated to the Organization model.

## Default Values

### MentraOS Settings Defaults
```typescript
{
  useOnboardMic: true,
  contextualDashboard: true,
  headUpAngle: 20,
  dashboardHeight: 90,
  dashboardDepth: 100,
  brightness: 50,
  autoBrightness: true,
  sensingEnabled: true,
  alwaysOnStatusBar: false,
  bypassVad: false,
  bypassAudioEncoding: false,
  metricSystemEnabled: true,
  enforceLocalTranscription: false
}
```

## Best Practices

1. **Always use `findOrCreateUser`** for user creation
2. **Sanitize all inputs** before database operations
3. **Use lean()** for read-only operations
4. **Update arrays atomically** using MongoDB operators
5. **Log all setting changes** for audit trail

## Example Usage

```typescript
// Find or create user
const user = await User.findOrCreateUser('alex@example.com');

// Install and run an app
await user.installApp('com.translator.app');
await user.addRunningApp('com.translator.app');

// Update app settings
await user.updateAppSettings('com.translator.app', [
  { key: 'language', value: 'spanish' }
]);

// Update system settings
user.augmentosSettings.brightness = 75;
user.augmentosSettings.useOnboardMic = false;
await user.save();

// Track glasses model
if (!user.glassesModels?.includes('Even Realities G1')) {
  user.glassesModels = [...(user.glassesModels || []), 'Even Realities G1'];
  await user.save();
}
```